/*
 * Copyright (C) 2008-2011 CBDP Consortium
 * 
 * All rights reserved.
 *
 * This software is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.
 * 
 * This software consists of contributions made by many individuals, 
 * listed below:
 *
 * Author: 	Xabier Laiseca <xabier.laiseca@deusto.es>
 * 			David Ausín <david.ausin@deusto.es>
 */
package cbdp.server.contextreasoner.model;

import java.util.Collection;

import cbdp.server.contextreasoner.model.exceptions.NotExistingPropertyException;
import cbdp.server.contextreasoner.model.exceptions.NotExistingInstanceException;
import cbdp.server.contextreasoner.model.exceptions.InvalidDatatypeException;
import cbdp.server.contextreasoner.model.exceptions.NotExistingPropertyInstanceException;
import cbdp.server.contextreasoner.model.exceptions.PreviouslyDeteledPropertyException;


/**
 * Represents an instance of the ontology.
 * @author Xabier Laiseca (University of Deusto)
 *
 */
public interface Instance
{
	/**
	 * Returns the identifier of the instance.
	 * @return the identifier of the instance.
	 */
	public String getIdentifier();
	
	
	/**
	 * Returns the class name of the instance.
	 * @return the class name of the instance.
	 */
	public String getOntologyClass();

	
	/**
	 * Adds a property to the instance that points to other instance of the ontology. 
	 * @param name the name of the property.
	 * @param objectName the identifier of the instance to point to.
	 * @throws NotExistingInstanceException thrown when the instance referenced by <code>objectName</code> does not exist.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 */
	public void addObjectDatatypeProperty(final String name, final String objectName) throws NotExistingInstanceException, NotExistingPropertyException;

	
	/**
	 * Adds a <code>boolean</code> property to the instance.
	 * @param name the name of the property.
	 * @param value the value of the property.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 * @throws InvalidDatatypeException thrown when the passed <code>value</code> is not compatible with the property type.
	 */
	public void addPrimitiveDatatypeProperty(final String name, final boolean value) throws NotExistingPropertyException, InvalidDatatypeException;
	
	/**
	 * Adds a <code>char</code> property to the instance.
	 * @param name the name of the property.
	 * @param value the value of the property.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 * @throws InvalidDatatypeException thrown when the passed <code>value</code> is not compatible with the property type.
	 */
	public void addPrimitiveDatatypeProperty(final String name, final char value) throws NotExistingPropertyException, InvalidDatatypeException;
	
	/**
	 * Adds a <code>double</code> property to the instance.
	 * @param name the name of the property.
	 * @param value the value of the property.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 * @throws InvalidDatatypeException thrown when the passed <code>value</code> is not compatible with the property type.
	 */
	public void addPrimitiveDatatypeProperty(final String name, final double value) throws NotExistingPropertyException, InvalidDatatypeException;
	
	/**
	 * Adds a <code>float</code> property to the instance.
	 * @param name the name of the property.
	 * @param value the value of the property.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 * @throws InvalidDatatypeException thrown when the passed <code>value</code> is not compatible with the property type.
	 */
	public void addPrimitiveDatatypeProperty(final String name, final float value) throws NotExistingPropertyException, InvalidDatatypeException;
	
	/**
	 * Adds a <code>int</code> property to the instance.
	 * @param name the name of the property.
	 * @param value the value of the property.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 * @throws InvalidDatatypeException thrown when the passed <code>value</code> is not compatible with the property type.
	 */
	public void addPrimitiveDatatypeProperty(final String name, final int value) throws NotExistingPropertyException, InvalidDatatypeException;
	
	/**
	 * Adds a <code>long</code> property to the instance.
	 * @param name the name of the property.
	 * @param value the value of the property.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 * @throws InvalidDatatypeException thrown when the passed <code>value</code> is not compatible with the property type.
	 */
	public void addPrimitiveDatatypeProperty(final String name, final long value) throws NotExistingPropertyException, InvalidDatatypeException;
	
	/**
	 * Adds a <code>String</code> property to the instance.
	 * @param name the name of the property.
	 * @param value the value of the property.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 * @throws InvalidDatatypeException thrown when the passed <code>value</code> is not compatible with the property type.
	 */
	public void addPrimitiveDatatypeProperty(final String name, final String value) throws NotExistingPropertyException, InvalidDatatypeException;

	
	/**
	 * Returns the identifier of the instance pointed by the property.
	 * @param name the name of the property.
	 * @return a object property of the given property name.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 * @throws NotExistingPropertyInstanceException thrown when the instance has not got the property defined. 
	 */
	public ObjectDatatypeProperty getObjectDatatypeProperty(final String name) throws NotExistingPropertyException, NotExistingPropertyInstanceException;
	
	/**
	 * Returns a collection of object properties of the given property name.
	 * @param name the name of the property.
	 * @return a collection of object properties of the given property name.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 */
	public Collection<ObjectDatatypeProperty> getObjectDatatypeProperties(final String name) throws NotExistingPropertyException;
	
	/**
	 * Returns a primitive datatype property of the given property name.
	 * @param name the name of the property.
	 * @return a primitive datatype property of the given property name.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 * @throws NotExistingPropertyInstanceException thrown when the instance has not got the property defined. 
	 */
	public PrimitiveDatatypeProperty getPrimitiveDatatypeProperty(final String name) throws NotExistingPropertyException, NotExistingPropertyInstanceException;
	
	
	/**
	 * Returns a collection of primitive datatype properties of the given property name.
	 * @param name the name of the property.
	 * @return a collection of primitive datatype properties of the given property name.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 */
	public Collection<PrimitiveDatatypeProperty> getPrimitiveDatatypeProperties(final String name) throws NotExistingPropertyException;
	
	/**
	 * Removes the property of the instance.
	 * @param property the property to remove.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 * @throws PreviouslyDeteledPropertyException thrown when the property has been previously deleted.
	 */
	public void deleteProperty(final GenericProperty property) throws NotExistingPropertyException, PreviouslyDeteledPropertyException;
	
	/**
	 * Removes all the existing properting of the instance.
	 * @param name the name of the property.
	 * @throws NotExistingPropertyException thrown when the property does not exist.
	 */
	public void deleteAllProperties(final String name) throws NotExistingPropertyException;
}